home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 1999 August / SGI Freeware 1999 August.iso / dist / fw_kdelibs.idb / usr / freeware / kde / include / kwizard.h.z / kwizard.h
Encoding:
C/C++ Source or Header  |  1999-01-26  |  10.0 KB  |  350 lines
  1. /*  This file is part of the KDE Libraries
  2.     Copyright (C) 1998 Thomas Tanghus (tanghus@earthling.net)
  3.  
  4.     This program is free software; you can redistribute it and/or
  5.     modify it under the terms of the GNU General Public
  6.     License as published by the Free Software Foundation; either
  7.     version 2 of the License, or (at your option) any later version.
  8.  
  9.     This program is distributed in the hope that it will be useful,
  10.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  11.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12.     General Public License for more details.
  13.  
  14.     You should have received a copy of the GNU Library General Public License
  15.     along with this library; see the file COPYING.LIB.  If not, write to
  16.     the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  17.     Boston, MA 02111-1307, USA.
  18. */  
  19.  
  20. #ifndef __KWIZARD_H
  21. #define __KWIZARD_H
  22.  
  23. #include <kapp.h>
  24. #include <qpopmenu.h>
  25. #include <qlabel.h>
  26. #include <qaccel.h>
  27. #include <qfont.h>
  28. #include <qpushbt.h>
  29. #include <qpainter.h>
  30. #include <qpen.h>
  31. #include <kdbtn.h>
  32. #include <kseparator.h>
  33. struct KWizProtected;
  34.  
  35. /**
  36. * KWizardPage holds information about the pages in the wizard. Given as
  37. * argument to @ref addPage.
  38. */
  39. struct KWizardPage
  40. {
  41.   QString title;
  42.   QWidget *w;
  43.   bool enabled;
  44.   int id;
  45. };
  46.  
  47.  
  48. #define NEXT klocale->translate("&Next >>")
  49. #define PREV klocale->translate("<< &Previous")
  50.  
  51.  
  52. /**
  53. * KWizard is a multi-purpose dialog. It is very useful for:
  54. *
  55. * - Configuration dialogs where the order in which the entries are filled is important.
  56. *
  57. * - Tutorials. Just create some HTML-widgets and feed them to a KWizard and your done (almost).
  58. *
  59. * - NoteBooks. KWizard is an integrated part of KNoteBook which provides a notebook
  60. *   dialog similar to the ones in OS/2 Warp 4.
  61. *
  62. * - Propably many other things...
  63. *
  64. * The dialog contains:
  65. *
  66. * - A title at the top of the page.
  67. *
  68. * - A separator.
  69. *
  70. * - The userprovided page-widget.
  71. *
  72. * - A separator.
  73. *
  74. * - A label indicating the pagination.
  75. *
  76. * - A Previous and a Next button.
  77. *
  78. * - Optionally Ok, Cancel and Help buttons.
  79. * 
  80. * @short KWizard
  81. * @author Thomas Tanghus <tanghus@earthling.net>
  82. * @version 0.1
  83. */
  84. class KWizard : public QWidget
  85. {
  86. friend class KNoteBook;
  87.     Q_OBJECT
  88.  
  89. public:
  90. /**
  91. * Constructor
  92. */
  93.     KWizard(QWidget *parent = 0, const char *name = 0, bool modal = false, WFlags f = 0);
  94. /**
  95. * Destructor
  96. */
  97.     ~KWizard();
  98. /**
  99. * Adds a page to the wizard.
  100. * The pages are numbered from 0-n where 0 is the page first added and n is the
  101. * page last added.
  102. * @param p KWizardPage containing the page data.
  103. *
  104. * @return Returns the id of the new page.
  105. */
  106.         int addPage(KWizardPage *p);
  107. /**
  108. * En/disable a specified page. If a page is disable its content will be grayd out
  109. * and it will not receive keyboard input.
  110. * @param page The page to en/disable.
  111. * @param state If 'state' is false the page will be disabled, otherwise it will be enabled.
  112. * @see KNoteBook#setPageEnabled
  113. */
  114.         void setPageEnabled(int page, bool state);
  115. /**
  116. * Check the state of the page.
  117. * @see #setPageEnabled
  118. * @return Returns true if the page is enabled, otherwise false.
  119. */
  120.         bool isPageEnabled(int page) { return pages->at(page)->enabled; };
  121. /**
  122. * Adds a Cancel button to the bottom of the dialog. The text will be a translated
  123. * version of the string '&Cancel' thereby giving it the shortcut key 'c'.
  124. * If any buttons are added a space will be created at the bottom of the dialog
  125. * to fit the buttons. When clicked the button will emit the @ref cancelclicked signal.
  126. * @see KLocale#translate
  127. */
  128.         void setCancelButton();
  129. /**
  130. * Adds a Cancel button to the bottom of the dialog.
  131. * @param text A user supplied text to write to the button.
  132. */
  133.         void setCancelButton(const char *text);
  134. /**
  135. * Adds a Default button to the bottom of the dialog. The text will be a translated
  136. * version of the string '&Default' thereby giving it the shortcut key 'd'.
  137. * If any buttons are added a space will be created at the bottom of the dialog
  138. * to fit the buttons. When clicked the button will emit the @ref defaultclicked signal.
  139. * @see KLocale#translate
  140. */
  141.         void setDefaultButton();
  142. /**
  143. * Adds a Default button to the bottom of the dialog.
  144. * @param text A user supplied text to write to the button.
  145. */
  146.         void setDefaultButton(const char *text);
  147. /**
  148. * Adds a Help button to the bottom right of the dialog. The text will be a translated
  149. * version of the string '&Help' thereby giving it the shortcut key 'h'.
  150. * If any buttons are added a space will be created at the bottom of the dialog
  151. * to fit the buttons. When clicked the button will emit the @ref helpclicked signal.
  152. * @see #getHelpButton
  153. */
  154.         void setHelpButton();
  155. /**
  156. * Adds a Help button to the bottom of the dialog. This button will generate the
  157. * signal @ref helpclicked where the int is the page to which the help was requested.
  158. * @see #getHelpButton
  159. * @param text A user supplied text to write to the button.
  160. */
  161.         void setHelpButton(const char *);
  162. /**
  163. * Adds an Ok button to the bottom right of the dialog. The text will be a translated
  164. * version of the string '&Ok' thereby giving it the shortcut key 'o'.
  165. * If any buttons are added a space will be created at the bottom of the dialog
  166. * to fit the buttons. When clicked the button will emit the @ref okclicked signal.
  167. * @see #getOkButton
  168. */
  169.         void setOkButton();
  170. /**
  171. * Adds an Ok button to the bottom of the dialog. This button will generate the
  172. * signal @ref okclicked where the int is the page to which the help was requested.
  173. * @see #getOkButton
  174. * @param text A user supplied text to write to the button.
  175. */
  176.         void setOkButton(const char *);
  177. /**
  178. * @see #setOkButton
  179. * @return Returns the Ok buttonwidget or 0L if no button is added.
  180. */
  181.         QButton * getOkButton();
  182. /**
  183. * @see #setCancelButton
  184. * @return Returns the Cancel buttonwidget or 0L if no button is added.
  185. */
  186.         QButton * getCancelButton();
  187. /**
  188. * @see #setDefaultButton
  189. * @return Returns the Default buttonwidget or 0L if no button is added.
  190. */
  191.         QButton * getDefaultButton();
  192. /**
  193. * @see #setHelpButton
  194. * @return Returns the Help buttonwidget or 0L if no button is added.
  195. */
  196.         QButton * getHelpButton();
  197. /**
  198. * getNextButton.
  199. * @return Returns the Next buttonwidget.
  200. */
  201.         QButton * getNextButton();
  202. /**
  203. * getPreviousButton
  204. * @return Returns the Previous buttonwidget.
  205. */
  206.         QButton * getPreviousButton();
  207. /**
  208. * @see #setEnableArrowButtons
  209. * @return Returns the left arrowbutton.
  210. */
  211.         KDirectionButton * getLeftArrow();
  212. /**
  213. * @see #setEnableArrowButtons
  214. * @return Returns the right arrowbutton.
  215. */
  216.         KDirectionButton * getRightArrow();
  217. /**
  218. * Let direction buttons reflect page.
  219. * @see #directionsReflectsPage
  220. * @param state If state is true the direction buttons (Previous and Next) will have the
  221. * title of the corresponding page.
  222. */
  223.         void setDirectionsReflectsPage(bool state);
  224. /**
  225. * @return Returns whether the direction buttons reflects the title of the corresponding page.
  226. *
  227. * @see #setDirectionsReflectsPage(bool state)
  228. */
  229.         bool directionsReflectsPage();
  230. /**
  231. * En/Disable the popup menu.
  232. * @see #enablePopupMenu
  233. * @param state If state is true a menu containing the pages in the wizard
  234. * will popup when the user RMB-clicks on the page-title.
  235. */
  236.         void setEnablePopupMenu(bool state);
  237. /**
  238. * @see #setEnablePopupMenu
  239. * @return Returns 'true' if the popupmenu is enabled.
  240. */
  241.         bool enablePopupMenu();
  242. /**
  243. * getMenu
  244. * @see #setEnablePopupMenu #enablePopupMenu
  245. * @return Returns the handle of the popup menu.
  246. */
  247.         QPopupMenu * getMenu();
  248. /**
  249. * En/Disable the arrow buttons at the rightmost of the title.
  250. * @param state If state is true two arrows will appear to the right of the pagination
  251. * allowing the user to change pages by clicking on them.
  252. * @see #enableArrowButtons
  253. */
  254.         void setEnableArrowButtons(bool state);
  255. /**
  256. * @see #setEnableArrowButtons
  257. * @return Returns 'true' if the arrow buttons are enabled.
  258. */
  259.         bool enableArrowButtons();
  260.         QSize sizeHint() { return minimumSize(); };
  261.         void adjustSize() { resize(sizeHint()); };
  262. /**
  263. * getTitle
  264. * @return Returns the title of a specified page. Used by KNoteBook
  265. * @param page The page to retrieve the title from.
  266. */
  267.         const char * getTitle(int page) { return pages->at(page)->title.data(); };
  268. /**
  269. * numPages
  270. * @return Returns the number of pages in the wizard.
  271. */
  272.         int numPages();
  273.  
  274. signals:
  275. /**
  276. * This signal is emitted when the user clicks on the Ok button.
  277. */
  278.         void okclicked();
  279. /**
  280. * This signal is emitted when the user clicks on the Cancel button.
  281. */
  282.         void cancelclicked();
  283. /**
  284. * This signal is emitted when the user clicks on the Default button.
  285. * The int is the page which was showing when default settings was requested.
  286. */
  287.         void defaultclicked(int);
  288. /**
  289. * This signal is emitted when the user clicks on the Help button.
  290. * The int is the page which was showing when help was requested.
  291. * @see #setHelpButton
  292. * <BR>
  293. * @see #getHelpButton
  294. */
  295.         void helpclicked(int);
  296. /**
  297. * This signal is emitted when a page is selected. The int is the page number
  298. */
  299.         void selected(int);
  300.  
  301. /**
  302. * This signal is emitted when the dialog is closed. Mainly usable if the dialog
  303. * is a top level widget.
  304. */
  305.         void closed();
  306.  
  307. /**
  308. * This signal is emitted when a popup menu is requested. This happens when the user
  309. * RMB-clicks somewhere in the title (not the titlebar). This is used by KNoteBook.
  310. */
  311.         void popup(QPoint);
  312. /**
  313. * This signal is used by KNoteBook.
  314. */
  315.         void nomorepages(bool, bool);
  316.  
  317. public slots:
  318. /*
  319. * Goto to a specified page.
  320. * @param page The page number to turn to.
  321. */
  322.         void gotoPage(int page);
  323.  
  324. protected slots:
  325.         void nextPage();
  326.     void previousPage();
  327.     void okClicked();
  328.     void cancelClicked();
  329.     void defaultClicked();
  330.         void helpClicked();
  331.  
  332. protected:
  333.         bool eventFilter( QObject *, QEvent * );
  334.         void closeEvent(QCloseEvent *);
  335.  
  336.         QSize pageSize();
  337.         void setSizes();
  338.         void resizeEvent(QResizeEvent *);
  339.         void paintEvent(QPaintEvent *);
  340.  
  341.         QList<KWizardPage> *pages;
  342.         //QList<QWidget> pages;
  343.         //QStrList titles;
  344.         KWizProtected *pwiz;
  345. };
  346.  
  347. #endif // __KWIZARD_H
  348.  
  349.  
  350.